TMAP 웹 API 개발자 가이드

1. TMAP 웹 API 개요

1.1 TMAP API 소개: 대한민국 1위 모빌리티 플랫폼

TMAP API는 단순한 지도 라이브러리가 아닌, 대한민국 모빌리티 시장을 선도하는 종합 플랫폼의 기술적 기반을 개발자에게 제공하는 서비스다.1 20년 이상 축적된 데이터와 기술력을 바탕으로, 현재 TMAP은 2,000만 명의 가입자와 65%에 달하는 시장 점유율을 기록하며 국내 최대 위치 기반 서비스로서의 입지를 공고히 하고 있다.1 개발자는 TMAP API를 통해 이러한 방대한 사용자 기반에서 생성되는 실시간 데이터와 고도로 정제된 지도 정보를 자신의 서비스에 직접 통합할 수 있다.

API의 핵심 경쟁력은 데이터의 양과 질, 그리고 실시간성에 있다. TMAP API는 오랜 기간 축적된 고품질, 고정밀 데이터를 기반으로 최고의 신뢰성을 보장한다.1 구체적으로 약 3,800만 건의 지번 주소, 800만 건의 새 주소, 530만 건의 기본 POI(Point of Interest, 관심 장소), 1,100만 건의 별칭 POI, 그리고 약 800만 건의 기업 특화 POI 등 국내 최대 규모의 지도 데이터를 제공한다.1 이 방대한 데이터는 단순한 지리 정보 제공을 넘어, 사용자의 다양한 검색 요구에 정확하게 부응하는 서비스 개발의 초석이 된다.

또한, TMAP API는 실시간 교통 정보의 정확성에서 독보적인 우위를 점한다. 사용자는 API를 통해 도로의 교통 상황을 실시간으로 확인하고 이를 지도 콘텐츠에 반영할 수 있다. 이를 기반으로 최적 경로를 재탐색하거나 사고, 공사, 정체 구간을 회피하는 등 동적인 상황 변화에 능동적으로 대응하는 지능형 길안내 서비스 구현이 가능하다.1 이러한 실시간성은 특히 물류, 배송, 관제와 같이 시간 효율성이 비즈니스의 성패를 좌우하는 분야에서 강력한 차별점으로 작용한다.

1.2 핵심 기능 그룹: 지도, 경로, 장소, 그리고 퍼즐(Puzzle)

TMAP API의 기능적 아키텍처는 네 가지 명확한 그룹으로 구성되어, 개발자가 서비스의 목적에 따라 필요한 기능을 체계적으로 조합하고 확장할 수 있도록 설계되었다. 이는 개발자가 API의 전체 구조를 직관적으로 파악하고, 특정 기능에 신속하게 접근하여 개발 효율성을 극대화하도록 돕는다.1

1. 지도(Map): 위치 기반 서비스의 가장 기본적인 시각적 요소를 담당한다. TMAP API는 세 가지 형태의 지도 서비스를 제공하여 다양한 개발 환경과 요구사항에 대응한다.1

• 벡터 지도(Vector Map): 유연한 스타일링과 고해상도 렌더링이 가능한 벡터 타일 기반 지도로, 동적인 지도 인터랙션과 커스터마이징에 최적화되어 있다.

• 래스터 지도(Raster Map): 전통적인 이미지 타일 기반 지도로, 범용성과 호환성이 높다.

• 정적 지도(Static Map): 특정 위치의 지도 이미지를 반환하는 API로, 동적인 상호작용이 필요 없는 간단한 위치 표시에 유용하다.3

2. 경로(Route): TMAP의 핵심 경쟁력인 길안내 및 최적화 기능을 제공하는 그룹이다. 실시간 교통정보를 기반으로 한 정교한 경로 계산은 TMAP API의 가장 강력한 기능 중 하나다.1

• 경로 안내: 자동차, 보행자 등 다양한 이동 수단에 최적화된 경로를 제공한다.

• 다중 경유지 안내 및 최적화: 여러 경유지를 방문하는 시나리오에서 최적의 방문 순서를 계산하여 총 이동 시간과 비용을 최소화한다. 이는 배송 및 물류 시스템의 핵심 로직을 구현하는 데 필수적이다.

3. 장소(Place): 지도 위의 특정 지점에 대한 정보를 검색하고 관리하는 기능들을 포함한다.

• POI(Point of Interest) 검색: 명칭, 주소, 전화번호 등 다양한 조건으로 관심 장소를 검색한다.3

• 지오코딩(Geocoding): 주소와 좌표를 상호 변환하는 기능으로, 사용자가 입력한 주소를 지도 위에 표시하거나 지도 위의 특정 지점의 주소를 확인하는 데 사용된다.3

• 지오펜싱(Geofencing): 특정 지역(시/도, 구/군, 읍/면/동 등)의 경계 데이터를 제공하여, 특정 차량이나 사용자가 해당 구역에 진입하거나 이탈하는 이벤트를 감지하는 등의 기능을 구현할 수 있다.3

4. 퍼즐(Puzzle): SK텔레콤의 통신 및 모빌리티 빅데이터를 분석, 가공하여 제공하는 고차원적인 데이터 인텔리전스 API 그룹이다. 이는 단순한 지리 정보를 넘어, 특정 지역이나 장소에 대한 깊이 있는 인사이트를 제공한다.1

• 장소 혼잡도: 특정 쇼핑몰, 공원 등의 실시간 혼잡도 정보를 제공한다.5

• 이동 및 여행 지수: SKT 이용자의 이동 행태 데이터를 분석하여 지역별 방문 통계, 체류 시간, 여행자 수 추정치 등을 제공한다.1

• 주거 생활 및 상권 분석: 특정 아파트 단지 주민의 생활 패턴이나 주변 상권의 인기도 등을 분석한 데이터를 제공한다.1

이러한 기능적 분리는 TMAP API가 단순한 지도 도구를 넘어, 기초적인 위치 서비스부터 데이터 기반의 복잡한 비즈니스 인텔리전스 애플리케이션까지 구축할 수 있는 포괄적인 플랫폼임을 보여준다. 개발자는 지도, 경로, 장소 API를 조합하여 기본적인 서비스를 구축하고, 퍼즐 API를 통해 서비스의 가치를 한 단계 높이는 데이터 기반의 차별화된 기능을 추가할 수 있다.

1.3 주요 활용 사례: 물류, 배송, 관제 시스템의 혁신

TMAP API는 이론적인 기능 명세를 넘어, 실제 산업 현장에서 복잡한 비즈니스 문제를 해결하며 그 가치를 입증하고 있다. 특히 물류, 배송, 관제 시스템 분야에서 TMAP API는 운영 효율성을 극대화하고 비용을 절감하는 핵심 솔루션으로 활용된다.

• 물류 및 배송 최적화: 다수의 배송지를 효율적으로 처리해야 하는 라스트마일(Last-mile) 배송 분야에서 TMAP의 ’경유지 최적화 API’는 핵심적인 역할을 수행한다. 예를 들어, 롯데마트는 오프라인 매장에서 고객이 결제한 상품을 2시간 내에 배송하는 시스템을 구축하면서 TMAP의 경로 API를 활용하여 배차 작업을 최적화했다.1 이는 수십, 수백 개의 배송지를 가진 배송 기사에게 최적의 방문 순서를 실시간으로 제공하여 총 이동 거리를 줄이고 배송 시간을 단축시키는 효과를 가져온다. 이마트 역시 온라인몰 주문을 고객이 원하는 시간대에 맞춰 배송하기 위해 TMAP의 경로 정보를 활용하여 배송 시간 예측 및 관리를 최적화하고 있다.5

• 실시간 관제 시스템: C&U 편의점의 물류 차량 관제 시스템은 TMAP API의 다각적 활용을 보여주는 대표적인 사례다.5 이 시스템은 단순히 차량의 현재 위치를 추적하는 것을 넘어, 다음과 같은 고도화된 기능을 구현한다.

• 최적 길안내: 실시간 교통 상황을 반영한 최적 경로를 운전자에게 제공하여 빠른 배송을 지원한다.

• 도착 시간 예측(ETA, Estimated Time of Arrival): 각 물류센터나 편의점에 차량이 도착할 예상 시간을 정확하게 예측하여 운영 효율성을 높인다.

• 지오펜싱(Geofencing) 기반 구역 관리: 각 차량의 담당 관할 구역을 지오펜싱으로 설정하고, 차량이 구역을 이탈하거나 진입할 때 알림을 발생시켜 효율적인 관리를 가능하게 한다.1

이러한 사례들은 TMAP API가 제공하는 정밀한 데이터와 강력한 연산 능력이 어떻게 기업의 핵심 운영 프로세스를 혁신하고 새로운 비즈니스 가치를 창출하는지를 명확히 보여준다. 개발자는 이러한 사례를 참고하여 자신의 서비스에 TMAP API를 어떻게 적용할 수 있을지에 대한 실용적인 아이디어를 얻을 수 있다.

2. API 사용 준비 및 인증

TMAP API를 사용하기 위해서는 SK open API 플랫폼에서 제공하는 인증 절차를 거쳐 고유한 인증 키(appKey)를 발급받아야 한다. 이 과정은 API 호출의 보안을 확보하고, 사용량을 관리하며, 서비스 접근을 제어하는 핵심적인 단계다.

2.1 인증 키(appKey) 발급 절차: 단계별 가이드

인증 키 발급은 단일 과정이 아니라, SK open API 플랫폼 내에서 ‘회원가입’, ‘앱 생성’, ‘상품 구매’, ’키 확인’의 네 단계로 구성된 체계적인 절차를 따른다. 이 구조는 개발자가 여러 프로젝트와 API 상품을 효율적으로 관리할 수 있도록 설계되었다.

• 1단계: SK open API 포털 회원가입

모든 절차는 SK open API 포털(https://openapi.sk.com/)에서 시작된다.6 포털은 T 아이디를 통한 통합 로그인을 지원하므로, 기존 T 아이디가 있다면 즉시 로그인할 수 있으며, 없다면 신규 T 아이디를 생성하여 가입을 진행한다.7 가입 시 ’개인회원’과 ‘사업자회원’ 중 하나를 선택해야 한다. 개인회원은 개인적인 용도로 API를 사용하는 경우에 적합하며, 사업자회원은 기업용 서비스 개발을 목적으로 하며 세금계산서 발행 및 추가적인 기술 지원이 필요할 경우 선택한다.7

• 2단계: 앱(App) 생성

회원가입 및 로그인 후, 대시보드의 ‘앱’ 메뉴로 이동하여 새로운 앱을 생성한다.8 ’앱’은 API를 호출하는 주체를 식별하는 논리적인 단위다. 개발자는 각 프로젝트나 서비스 환경(예: 개발용, 스테이징용, 운영용)에 따라 별도의 앱을 생성하여 관리하는 것이 권장된다. ‘앱 만들기’ 버튼을 클릭하고 앱 이름을 입력하면 고유한 앱이 생성된다.8 이 앱 단위로 API 사용량이 집계되고, 인증 키가 발급되며, 접근 제어 정책이 적용된다.

• 3단계: TMAP API 상품 구매(사용 신청)

앱 생성이 완료되면, 해당 앱에서 사용할 API 상품을 추가해야 한다. SK open API 포털의 상품 목록에서 ‘TMAP’ 카테고리를 선택하고, 사용하려는 API 상품(예: TMAP API 무료/유료 버전)을 찾아 ‘사용하기’ 또는 ’구매하기’를 진행한다.7 무료 버전의 경우 별도의 결제 절차 없이 약관 동의만으로 사용 신청이 완료된다.6 이 과정을 통해 생성된 앱과 TMAP API 서비스가 연결된다.

• 4단계: appKey 확인

상품 구매가 완료되면, 다시 대시보드의 ‘앱’ 메뉴로 돌아와 생성한 앱의 상세 정보 페이지로 이동한다. 상세 페이지 내의 ‘앱키(appKey)’ 탭에서 발급된 고유한 인증 키 문자열을 확인할 수 있다.8 이 appKey는 이후 모든 TMAP API를 호출할 때 HTTP 헤더에 포함되어야 하는 핵심 인증 정보다. 보안상의 이유로 appKey가 외부에 노출된 경우, 해당 페이지에서 키를 재발급할 수 있다.9

이처럼 ’앱’을 중심으로 API 접근 권한을 관리하는 모델은 높은 유연성과 보안성을 제공한다. 하나의 앱에 여러 SK open API 상품(예: TMAP, NUGU)을 연결하여 단일 appKey로 관리할 수 있으며, 프로젝트별로 앱을 분리하여 사용량 모니터링과 보안 정책(예: IP 화이트리스트 설정)을 독립적으로 운영할 수 있다.9 이는 복잡한 시스템을 구축하는 개발자에게 체계적인 API 관리 환경을 제공한다.

2.2 API 호출 기본 규약

모든 TMAP API 요청은 일관된 기본 규약을 준수해야 한다. 이는 플랫폼의 안정성과 예측 가능성을 보장하기 위함이다.

• 프로토콜: 모든 API 서비스에 대한 요청은 HTTP 프로토콜을 사용한다.11 보안 연결을 위한

HTTPS가 권장된다.

• 요청 헤더(Request Headers): 모든 API 호출 시, HTTP 요청 헤더에 다음 두 가지 정보를 반드시 포함해야 한다.11

• appKey: 2.1절에서 발급받은 32자리의 고유 인증 키를 이 헤더에 담아 전송한다. 이 값이 누락되거나 유효하지 않을 경우, API 게이트웨이는 401 Unauthorized 또는 403 Forbidden 에러를 반환한다.

• Accept: 서버로부터 수신하고자 하는 응답 데이터의 형식을 지정한다. TMAP API는 application/json (기본값), application/xml, application/javascript (JSONP) 등 다양한 형식을 지원한다.13 특별한 이유가 없는 한, 현대적인 웹 개발 환경에서는 application/json 사용이 권장된다.

• 요청 파라미터: API에 전달하는 데이터는 HTTP 메소드에 따라 적절한 방식으로 인코딩 및 전송되어야 한다.

• GET 요청: 파라미터는 URL의 일부인 쿼리 스트링(Query String)으로 전달된다. 각 파라미터는 key=value 형태로 구성되며, 여러 파라미터는 앰퍼샌드(&)로 구분한다. 파라미터 값에 특수문자나 한글이 포함될 경우, 반드시 UTF-8 기반의 URL 인코딩을 적용해야 한다.11

• POST 요청: 파라미터는 HTTP 요청의 본문(Request Body)에 담겨 전송된다. 일반적으로 application/x-www-form-urlencoded 또는 application/json 형식을 사용하며, 이는 각 API 명세에 따라 다르다.

이러한 기본 규약을 준수하는 것은 TMAP API와의 성공적인 통신을 위한 첫걸음이다.

2.3 사용량 정책 및 한도(Quota)

TMAP API는 안정적인 서비스 제공과 시스템 부하 관리를 위해 API 호출 횟수를 제한하는 사용량 한도(Quota) 정책을 운영한다.15 개발자는 이 정책을 명확히 이해하고 자신의 서비스 트래픽을 예측하여 적절한 요금제를 선택해야 한다.

무료 요금제의 경우, 각 API별로 일일 호출량 한도가 설정되어 있다. 예를 들어, 특정 시점의 정책에 따라 POI 검색은 일일 50,000회, 경로 안내는 일일 1,000회까지 무료로 호출할 수 있다.15 이 한도는 서비스의 초기 개발 및 테스트 단계에서는 충분할 수 있으나, 상용 서비스로 전환하여 사용자가 증가하면 한도를 초과할 수 있다.

API 호출량이 설정된 한도를 초과하면, API 게이트웨이는 429 Too Many Requests 또는 429 QUOTA_EXCEEDED 에러를 반환하며 더 이상의 요청을 처리하지 않는다.17 이는 서비스 장애로 이어질 수 있으므로, 사용량 관리는 매우 중요하다.

개발자는 SK open API 포털의 대시보드를 통해 자신이 생성한 앱의 API별 실시간 사용량을 지속적으로 모니터링할 수 있다.19 대시보드는 현재까지의 누적 사용량과 잔여 호출량을 시각적으로 보여주어 한도 소진을 예측하는 데 도움을 준다. 또한, 특정 사용량(예: 80%, 90%)에 도달했을 때 SMS 알림을 받도록 설정하여 예기치 않은 서비스 중단을 방지할 수 있다.19

서비스 규모가 확장되어 무료 한도를 초과할 것으로 예상되는 경우, 개발자는 유료 요금제로 전환하거나 ‘한도 증설 요청’ 기능을 통해 일일 사용량을 증설할 수 있다.19 이는 안정적인 서비스 운영을 위한 필수적인 절차다.

3. 핵심 API 명세: 경로 탐색

TMAP API의 핵심 가치는 실시간 교통 정보를 반영한 정교한 경로 탐색 기능에 있다. ’자동차 경로 안내 API’는 이러한 TMAP의 기술력이 집약된 대표적인 엔드포인트로, 개발자는 이를 통해 단순한 두 점 간의 경로를 넘어, 복잡한 비즈니스 요구사항에 부합하는 최적화된 이동 경로를 얻을 수 있다.

3.1 자동차 경로 안내 API (/routes)

• Endpoint: POST https://apis.openapi.sk.com/tmap/routes 11

• 설명: 이 API는 출발지, 목적지, 그리고 선택적으로 최대 5개의 경유지를 입력받아 자동차 이동에 최적화된 경로 정보를 반환한다. 응답 데이터는 GeoJSON 표준 형식을 따르며, 경로를 구성하는 상세한 좌표 목록뿐만 아니라, 총 예상 소요 시간, 총 거리, 구간별 회전 정보(Turn-by-turn), 도로명, 통행 요금, 예상 택시 요금 등 풍부한 정보를 포함한다.11 이를 통해 개발자는 지도 위에 경로를 시각화하는 것은 물론, 상세한 네비게이션 안내 기능을 구현할 수 있다.

3.2 요청(Request) 명세

해당 API는 POST 메소드를 사용하며, 요청 파라미터는 Request Body에 application/x-www-form-urlencoded 형식으로 전달된다. 헤더에는 appKey가 필수적으로 포함되어야 한다.

Table 1: 자동차 경로 안내 요청 파라미터

특히 주목할 점은 endPoiId와 endRpFlag 파라미터다. 이들은 ‘장소(POI) 통합 검색’ API의 응답 값과 직접적으로 연동된다. 단순히 좌표만 사용하는 대신, POI 검색을 통해 얻은 이 값들을 함께 전달하면 TMAP의 방대한 POI 데이터베이스에 저장된 추가 정보(예: 건물의 정확한 주 출입구 위치)를 활용하여 훨씬 더 정확하고 사용자 친화적인 경로 안내가 가능하다. 따라서 ‘검색 후 경로 탐색(Search-then-Route)’ 패턴은 TMAP API를 활용하는 최적의 방식으로 권장된다.

3.3 응답(Response) 명세

API는 성공적으로 경로를 탐색하면 HTTP 200 OK 상태 코드와 함께 GeoJSON 형식의 응답 본문을 반환한다. GeoJSON 객체의 features 배열에는 경로를 구성하는 각 지점(Point)과 구간(LineString)의 정보가 순서대로 담겨 있다.

Table 2: 자동차 경로 안내 응답 데이터 구조 (GeoJSON features 배열 내 객체)

응답 데이터 구조에서 핵심은 features 배열의 첫 번째 요소(index가 0이고 properties.pointType이 ’S’인 객체)의 properties 객체에 총 거리, 총 시간 등 요약 정보가 포함된다는 점이다.21 개발자는 이 요약 정보를 사용자에게 먼저 제시하고, 이후

features 배열을 순회하며 각 구간의 geometry.coordinates를 연결하여 지도에 경로선을 그리거나, properties.description을 이용해 턴바이턴 안내를 제공할 수 있다.

3.4 요청 및 응답 예시 (cURL)

다음은 서울시청(출발지)에서 SK T타워(목적지)까지의 자동차 경로를 탐색하는 cURL 요청 예시다.

curl --request POST \
--url 'https://apis.openapi.sk.com/tmap/routes' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'appKey: {YOUR_APP_KEY}' \
--data 'startX=126.978710&startY=37.566892&endX=126.985023&endY=37.566481&startName=%EC%84%9C%EC%9A%B8%EC%8B%9C%EC%B2%AD&endName=SK%20T%ED%83%80%EC%9B%8C&searchOption=0&resCoordType=WGS84GEO&reqCoordType=WGS84GEO'

위 요청에 대한 서버의 JSON 응답 예시는 다음과 같은 구조를 가진다.

{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [126.978710, 37.566892]
},
"properties": {
"totalDistance": 1523,
"totalTime": 334,
"totalFare": 0,
"taxiFare": 3800,
"index": 0,
"pointIndex": 0,
"name": "서울시청",
"description": "출발",
"pointType": "S"
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [126.978710, 37.566892],
[126.978810, 37.566920]
},
"properties": {
"index": 1,
"lineIndex": 1,
"name": "세종대로",
"description": "세종대로을 따라 127m 이동",
"distance": 127,
"time": 28,
"roadType": 7
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [126.979920, 37.567430]
},
"properties": {
"index": 2,
"pointIndex": 1,
"name": "",
"description": "우회전 후 23m 이동",
"turnType": 13,
"pointType": "N"
}
},
//... more features...
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [126.985023, 37.566481]
},
"properties": {
"index": 10,
"pointIndex": 5,
"name": "SK T타워",
"description": "도착",
"pointType": "E"
}
}
]
}

4. 핵심 API 명세: 장소 검색

위치 기반 서비스의 사용자 경험은 ’검색’에서 시작된다. 사용자가 원하는 장소를 얼마나 빠르고 정확하게 찾을 수 있는지가 서비스의 첫인상을 결정한다. TMAP의 ’장소(POI) 통합 검색 API’는 방대한 데이터베이스와 정교한 검색 로직을 바탕으로 이러한 핵심 요구사항을 충족시키는 강력한 도구다.

4.1 장소(POI) 통합 검색 API (/pois)

• Endpoint: GET https://apis.openapi.sk.com/tmap/pois 12

• 설명: 이 API는 시설물명, 상호, 주소(지번/도로명), 전화번호 등 다양한 형태의 키워드를 입력받아 관련된 관심 장소(POI) 목록을 반환한다.12 검색 결과에는 각 POI의 명칭, 주소, 전화번호와 같은 기본 정보는 물론, 지도에 표시하기 위한 정확한 좌표(

noorLat, noorLon)와 경로 탐색 시 정확도를 높여주는 고유 식별자(id, pkey, rpFlag)가 포함된다.12 또한, 특정 지점을 중심으로 반경 내 검색, 지역 코드(법정동 코드)를 이용한 지역 한정 검색 등 고도화된 검색 옵션을 제공하여 개발자가 다양한 시나리오에 맞는 검색 기능을 구현할 수 있도록 지원한다.22

4.2 요청(Request) 명세

해당 API는 GET 메소드를 사용하며, 모든 요청 파라미터는 URL의 쿼리 스트링으로 전달된다. 헤더에는 appKey가 필수적으로 포함되어야 한다.

Table 3: POI 통합 검색 요청 파라미터

이 파라미터들을 조합함으로써 매우 정교한 검색 로직을 구현할 수 있다. 예를 들어, 특정 좌표(centerLon, centerLat)를 중심으로 반경 1km(radius=1000) 내의 ‘편의점’(searchKeyword)을 거리순(searchtypCd=R)으로 10개(count=10) 찾아오는 기능은 이 파라미터들의 조합으로 간단하게 구현된다. 이는 ’내 주변 OOO 찾기’와 같은 LBS(Location-Based Service)의 핵심 기능을 구현하는 데 매우 유용하다.

4.3 응답(Response) 명세

API는 성공적으로 검색을 수행하면 HTTP 200 OK 상태 코드와 함께 검색 결과를 담은 JSON 객체를 반환한다.

Table 4: POI 통합 검색 응답 데이터 구조

응답 데이터에서 가장 중요한 필드는 id, pkey, noorLat, noorLon, rpFlag이다. noorLat과 noorLon은 검색 결과를 지도에 마커로 표시하는 데 사용된다. 사용자가 특정 POI를 선택하면, 해당 POI의 id를 이용해 ’장소 상세 정보 검색 API’를 호출하여 더 자세한 정보를 얻을 수 있다. 또한, pkey와 rpFlag, 그리고 좌표를 ’자동차 경로 안내 API’의 파라미터로 전달하여 해당 지점까지의 최적 경로를 탐색할 수 있다. 이처럼 POI 검색 API는 다른 TMAP API들과 유기적으로 연동되는 데이터 허브 역할을 수행한다.

4.4 요청 및 응답 예시 (cURL)

다음은 ’SK T타워’를 검색하는 cURL GET 요청의 예시다.22

curl --request GET \
--url 'https://apis.openapi.sk.com/tmap/pois?version=1&searchKeyword=SK%20T%ED%83%80%EC%9B%8C&count=1' \
--header 'Accept: application/json' \
--header 'appKey: {YOUR_APP_KEY}'

위 요청에 대한 서버의 JSON 응답 예시는 다음과 같은 구조를 가진다.

{
"searchPoiInfo": {
"totalCount": "1",
"count": "1",
"page": "1",
"pois": {
"poi":
},
"desc": "SK텔레콤의 본사 빌딩으로..."
}
]
}
}
}

5. 에러 처리 및 문제 해결

안정적인 애플리케이션을 구축하기 위해서는 API 호출 시 발생할 수 있는 다양한 오류 상황에 효과적으로 대응하는 것이 필수적이다. TMAP API는 오류 발생 시 표준화된 형식의 에러 코드를 반환하여 개발자가 문제의 원인을 신속하게 파악하고 해결할 수 있도록 지원한다. 에러는 크게 두 가지 범주로 나뉜다: 인증, 권한, 사용량 등 API 호출의 전처리 단계에서 발생하는 ’API 게이트웨이 공통 에러’와, 요청 파라미터의 유효성 등 개별 API의 비즈니스 로직과 관련된 ’TMAP API 고유 에러’다.

5.1 에러 응답 구조

API 호출이 실패하면, 서버는 200 OK가 아닌 4xx 또는 5xx 계열의 HTTP 상태 코드와 함께 문제의 원인을 설명하는 JSON 형식의 응답 본문을 반환한다. 일반적인 에러 응답 구조는 다음과 같다.

{
"error": {
"id": "string",
"category": "string",
"code": "string",
"message": "string"
}
}

• id: 에러의 고유 식별자.

• category: 에러가 발생한 시스템 또는 API의 분류 (예: gw for Gateway, tmap for TMAP API).

• code: 에러의 종류를 나타내는 코드.

• message: 에러에 대한 사람이 읽을 수 있는 설명.

개발자는 이 구조를 파싱하여 프로그램적으로 에러를 처리하거나 사용자에게 적절한 안내 메시지를 표시할 수 있다.

5.2 API 게이트웨이 공통 에러 코드

이 에러들은 SK open API 플랫폼의 게이트웨이 단에서 발생하는 문제로, TMAP API뿐만 아니라 플랫폼의 모든 API에 공통적으로 적용된다. 주로 인증, 권한, 사용량 초과와 관련이 있다.

Table 5: API 게이트웨이 공통 에러

자료: 17

5.3 TMAP API 고유 에러 코드

이 에러들은 API 게이트웨이를 성공적으로 통과한 후, TMAP API 서버 내부의 로직을 처리하는 과정에서 발생하는 문제들이다. 주로 요청 파라미터의 형식, 값의 범위, 데이터의 유효성과 관련이 있다.

Table 6: TMAP API 고유 에러

자료: 18

효과적인 에러 처리는 애플리케이션의 견고성을 높이는 핵심 요소다. 개발자는 try-catch 구문 등을 활용하여 API 호출부를 감싸고, 반환된 HTTP 상태 코드와 에러 메시지를 분석하여 각 상황에 맞는 분기 처리를 구현해야 한다. 예를 들어, 429 QUOTA_EXCEEDED 에러 발생 시 사용자에게 서비스 이용이 일시적으로 제한됨을 알리고, 204 No Content의 경우 “검색 결과가 없습니다“와 같은 명확한 메시지를 표시하는 것이 좋은 사용자 경험을 제공하는 방법이다.

6. 참고 자료

1. TMAP - SK open API, https://openapi.sk.com/products/detail?svcSeq=4
2. T map for Biz., http://moville.nate.com/files/images/solution/T_map_API_product.pdf
3. TMAP 소개 - SK open API 소개, https://skopenapi.readme.io/reference/t-map-%EC%86%8C%EA%B0%9C
4. SK open API 소개, https://skopenapi.readme.io/reference/%EC%86%8C%EA%B0%9C
5. T MAP API, https://tmapapi.tmapmobility.com/
6. T map API 사용해 지도 띄우기 - 소더코드의 개발자들 그리고, https://sothecode.tistory.com/83
7. SK OPEN API 이용절차 - Guide | TMAP 대중교통 API, https://transit.tmapmobility.com/guide
8. 앱 사용하기 - SK open API 소개, https://skopenapi.readme.io/reference/%EC%95%B1-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0
9. SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=126
10. [React] T Map API (1) : 가입하기 - 개발 공부방 - 티스토리, https://zindex.tistory.com/298
11. 자동차 경로 안내 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=46
12. 장소 통합 검색 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=12
13. 장소 상세 정보 검색 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=13
14. 자동차 경로안내 - SK open API 소개, https://skopenapi.readme.io/reference/%EC%9E%90%EB%8F%99%EC%B0%A8-%EA%B2%BD%EB%A1%9C%EC%95%88%EB%82%B4
15. T map OpenAPI : happycgi, http://happycgi.com/15551
16. :: 소식 :: 공지사항 :: [쿠팡] OPENAPI 속도제한 정책 및 기존 OPENAPI 키 삭제 안내 - :: 윈셀링 ::, https://winselling.co.kr/notice/winselling/detail/103
17. 에러 코드 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=318
18. 에러 코드 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=58
19. 상품 사용 신청하기 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=127
20. openapi.sk.com, https://openapi.sk.com/products/detail?linkMenuSeq=46#:~:text=https%3A%2F%2Fapis.openapi.sk.com%2Ftmap%2Froutes&text=%EC%B6%9C%EB%B0%9C%EC%A7%80%2C%20%EB%AA%A9%EC%A0%81%EC%A7%80%2C%20%EA%B2%BD%EC%9C%A0%EC%A7%80%EB%A5%BC%20%EB%93%B1%EB%A1%9D,%EB%93%B1)%EB%A5%BC%20%ED%8C%8C%EC%95%85%ED%95%A0%20%EC%88%98%20%EC%9E%88%EC%8A%B5%EB%8B%88%EB%8B%A4.를 파악할 수 있습니다.)
21. 경로안내 샘플예제 - SK open API 소개, https://skopenapi.readme.io/reference/%EA%B2%BD%EB%A1%9C%EC%95%88%EB%82%B4-%EC%83%98%ED%94%8C%EC%98%88%EC%A0%9C
22. 장소(POI) 통합 검색 - SK open API 소개, https://skopenapi.readme.io/reference/%EC%9E%A5%EC%86%8C%ED%86%B5%ED%95%A9%EA%B2%80%EC%83%89
23. 장소(POI) 통합 검색 - ReadMe, https://tmap-skopenapi.readme.io/reference/%EC%9E%A5%EC%86%8C%ED%86%B5%ED%95%A9%EA%B2%80%EC%83%89
24. Error Code - SK open API 소개, https://skopenapi.readme.io/reference/error-code-12